docs: stand up Docusaurus site for ongoing docs work#1507
Conversation
jeffredodd
changed the title
|
@copilot Can you catch us up here to the latest? Make sure any docs that changes are edited and updated here as well. |
Merged latest
Note: main also added several new components (Employee Dashboard, EmployeeList, PolicySettings, SelectEmployees, address management) that don't yet have dedicated pages under |
|
Warning According to your organization's Security Policy, you must resolve all "Block" alerts before proceeding. It is recommended to resolve "Warn" alerts too. For more information please check in at #security-help. For License Policy Violations please also tag @Aoife in #security-help.
Ignoring alerts on:
|
|
@copilot Can you fix the CI here? |
CI fixes pushed in 237ce7a:
Local verification: Two remaining CI signals are unrelated to my doc work:
|
|
@SocketSecurity ignore npm/lunr-languages@1.14 |
jeffredodd
changed the title
|
@SocketSecurity ignore npm/lunr-languages@1.14.0 |
|
@SocketSecurity ignore npm/typescript@5.8.3 |
|
@copilot Can you remove all the .md doc changes to actual docs and match and take whats on our latest origin/main branch? We also will need to update the sidebar links. Basically, lets just ship the infrastructure of this without any doc changes so we can begin to iterate. I do expect the main page that we created/generated will need to remain. |
Done in afe9215. Reverted all of
Also pulled in the latest from |
Fresh Eyes ReviewFound 7 issues in this PR. PR Description Issues
Download findings.json — drag the file into Claude or use Please 👍🏽 👎🏽 if you found this useful. Generated by Fresh Eyes Reviewer. Get help in #ai-code-reviews |
|
@SocketSecurity ignore npm/lunr-languages@1.17.0 |
|
@SocketSecurity ignore npm/lunr-languages@1.20.0 |
|
@cursoragent Can you review this and fix the merge conflicts and rebase the branch? I want to make sure we have all the latest docs from main. Main should really be our source of truth for the docs. |
SummarySuccessfully rebased What I did
Current stateThe branch now contains only infrastructure changes:
All documentation content matches main exactly, allowing you to iterate on content separately from the infrastructure.   |
cursor
Bot
force-pushed
the
jdj/docs-docusaurus
branch
from
cdb8b14 to
bb65666
Compare
jeffredodd
force-pushed
the
jdj/docs-docusaurus
branch
from
bb65666 to
74c0fbf
Compare
|
@cursoragent Can you review all the feedback and make updates to issues you see from feedback? |
|
Perfect! I've successfully addressed all the actionable feedback from the Fresh Eyes review: Changes Made✅ Accessibility Fixes (WCAG Compliance)Fixed 4 SVG icon accessibility issues:
Fixed heading hierarchy (WCAG 1.3.1):
✅ Configuration ConsistencyUpdated Docusaurus config:
📝 Note on PR DescriptionThe Fresh Eyes bot identified several claims in the PR description that don't match the current infrastructure-only state:
Since the PR description is not agent-managed, you'll want to update it manually to reflect that this PR currently ships only the Docusaurus infrastructure as an iteration foundation. All code issues have been fixed and pushed to the branch. |
![gusto-fresh-eyes[bot]](https://avatars.githubusercontent.com/in/3457483?s=60&v=4){kind=small}
|
|
||
| onBrokenLinks: 'warn', |
There was a problem hiding this comment.
🟡 Minor | logic-errors
Config sets onBrokenLinks: 'warn' and onBrokenAnchors: 'warn', but the PR description explicitly claims strict enforcement with 'throw' so broken links fail the build. With 'warn', broken links will not cause build failures and regressions can ship silently. If the intent described in the PR is correct, these should be 'throw'.
Please 👍🏽 👎🏽 if you found this useful. Generated by Fresh Eyes Reviewer. Get help in #ai-code-reviews
There was a problem hiding this comment.
Done! I've fixed the configuration mismatch.
Change Made
Updated website/docusaurus.config.ts:
- Changed
onBrokenLinks: 'warn'→onBrokenLinks: 'throw' - Changed
onBrokenAnchors: 'warn'→onBrokenAnchors: 'throw'
This now matches the PR description's claim of "strict broken-link enforcement" and ensures the build will fail if any broken links or anchors are introduced, preventing regressions from shipping silently.
The changes have been committed and pushed to the branch.
| .api-method > .menu__link, | ||
| .schema > .menu__link { | ||
| align-items: center; | ||
| justify-content: start; | ||
| } | ||
|
|
||
| .api-method > .menu__link::before, | ||
| .schema > .menu__link::before { | ||
| width: 55px; | ||
| height: 20px; | ||
| font-size: 12px; | ||
| line-height: 20px; | ||
| text-transform: uppercase; | ||
| font-weight: 600; | ||
| border-radius: 0.25rem; | ||
| border: 1px solid transparent; | ||
| margin-right: var(--ifm-spacing-horizontal); | ||
| text-align: center; | ||
| flex-shrink: 0; | ||
| color: white; | ||
| } | ||
|
|
||
| .get > .menu__link::before { | ||
| content: 'get'; | ||
| background-color: var(--openapi-code-green, #009d77); | ||
| } | ||
|
|
||
| .post > .menu__link::before { | ||
| content: 'post'; | ||
| background-color: var(--openapi-code-blue, #0072ce); | ||
| } | ||
|
|
||
| .put > .menu__link::before { | ||
| content: 'put'; | ||
| background-color: var(--openapi-code-orange, #d97706); | ||
| } | ||
|
|
||
| .delete > .menu__link::before { | ||
| content: 'del'; | ||
| background-color: var(--openapi-code-red, #dc2626); | ||
| } | ||
|
|
||
| .patch > .menu__link::before { | ||
| content: 'patch'; | ||
| background-color: var(--openapi-code-orange, #d97706); | ||
| } | ||
|
|
||
| .head > .menu__link::before { | ||
| content: 'head'; | ||
| background-color: var(--ifm-color-secondary-darkest, #6b7280); | ||
| } | ||
|
|
||
| .schema > .menu__link::before { | ||
| content: 'schema'; | ||
| background-color: var(--ifm-color-secondary-darkest, #6b7280); | ||
| } | ||
|
|
||
| /* ── API tag page cards ── */ |
There was a problem hiding this comment.
🟡 Minor | premature-abstraction-dead-css
~60 lines of CSS targeting .api-method, .get, .post, .put, .delete, .patch, .head, .schema badge selectors and .docItemContainer article .card styles reference an OpenAPI documentation plugin that is not installed (not in package.json) and not configured (not in docusaurus.config.ts plugins/presets). This is premature styling for a feature that doesn't exist yet — no consumer will hit these selectors. Consider removing these rules and adding them when the OpenAPI plugin is actually integrated.
Please 👍🏽 👎🏽 if you found this useful. Generated by Fresh Eyes Reviewer. Get help in #ai-code-reviews
jeffredodd
force-pushed
the
jdj/docs-docusaurus
branch
from
af17d7c to
466076c
Compare
Adds the Docusaurus site under `website/` and the supporting ignore/lint config additions. Sources `docs/` content from `main` unchanged. Squashed from the prior `jdj/docs-docusaurus` history (6ed6440, bc6ae3c, 57c026b, ef2f63a, 74c0fbf, 47e48f6, af17d7c) and rebased onto latest main so all `.md` content reflects current `origin/main`. Co-authored-by: Cursor <cursoragent@cursor.com>
Adds root-level npm script aliases so the Docusaurus dev server, build, and supporting commands can be invoked without `cd website`. - `npm run docs:site` — live dev server (http://localhost:3000) - `npm run docs:site:build` — production build - `npm run docs:site:serve` — serve production build - `npm run docs:site:install` — install website dependencies - `npm run docs:site:clear` — clear Docusaurus cache Co-authored-by: Cursor <cursoragent@cursor.com>
jeffredodd
force-pushed
the
jdj/docs-docusaurus
branch
from
466076c to
ee408d2
Compare
Now that the old ReadMe `docs`/`docs:watch`/`docs:sync`/`docs:publish` scripts have been removed from main, the `docs:site:*` namespace is no longer needed. Use the shorter `docs:*` names: - `npm run docs` (was `docs:site`) - `npm run docs:build` (was `docs:site:build`) - `npm run docs:serve` (was `docs:site:serve`) - `npm run docs:install` (was `docs:site:install`) - `npm run docs:clear` (was `docs:site:clear`) `docs:events` (unrelated event-type emitter) is unchanged. Co-authored-by: Cursor <cursoragent@cursor.com>
The `website/` directory naming conflicts with the broader concept of docs in this repo (docs/, docs:* scripts) and reads oddly given this folder contains the Docusaurus documentation site. Rename to `docs-site/` and update all path references in `package.json` scripts, `.gitignore`, `.prettierignore`, and `eslint.config.mjs`. Pure rename — no behavior change. `npm run docs:build` still produces an identical build. Co-authored-by: Cursor <cursoragent@cursor.com>
Cleanup pass on the new Docusaurus site: - `src/pages/index.tsx`, `src/theme/NotFound/Content/index.tsx`: switch return types from `JSX.Element` (global namespace, brittle across React versions) to `ReactNode`. Use `useBaseUrl` for hero logo `<img src>` paths so they survive non-root `baseUrl` deployments. - `docusaurus.config.ts`: drop the `path-browserify` webpack polyfill plugin — nothing in the site imports `path` and it was leftover from an OpenAPI plugin template. - `package.json`: drop the now-unused `path-browserify` dependency. - `src/css/custom.css`: remove ~100 lines of `.api-method`/`.schema`/ HTTP-method badge selectors and `.docItemContainer article .card` styling — both only target classes emitted by `docusaurus-plugin-openapi-docs`, which we aren't loading. - `.gitignore`, `.prettierignore`, `docs-site/.gitignore`: remove `docs/api/` and `openapi/` ignores tied to the same unused plugin. Net effect: -129 / +12 with no functional change. `npm run docs:build` still succeeds end-to-end. Co-authored-by: Cursor <cursoragent@cursor.com>
…ensations Three references to SDK source files (`Compensation.tsx`, `Dashboard.tsx`, `payRateCalculator.ts`) were authored as relative links like `[label](../../src/foo.tsx)`. These work when reading the markdown on GitHub but resolve outside the served site under Docusaurus, breaking the `onBrokenLinks: 'throw'` build check. Strip the link wrapping and leave the paths as code spans. Files remain discoverable on GitHub via repo navigation, and the served site no longer has dead links. The other reference links in the same section (gws-flows, ZenPayroll, public/internal docs) are absolute external URLs and are unchanged. Co-authored-by: Cursor <cursoragent@cursor.com>
Tightens up the hand-written HTML in the docs-site after a review pass:
- Drop duplicate landmarks: `<header>` on the hero and `<main>` in the
404 page were nested inside Docusaurus's own `<header>` (navbar) and
`<main>` (Layout). Two `<header>` landmarks on one page and a `<main>`
inside `<main>` are both invalid HTML and confuse screen readers.
Use `<section>` / `<div>` instead.
- Fix duplicate alt text on hero brand logos. Both `<img>` tags are
always in the DOM (CSS toggles display), but the hidden one is
`display: none` so it's removed from the accessibility tree. Use the
same `alt="Gusto Embedded"` on both — only the visible one is
announced.
- Replace the `<h2 className="sr-only">Key Features</h2>` landmark
label on the features section with `aria-label="Key features"` on the
`<section>`. Same accessibility outcome without needing a custom
visually-hidden utility class.
- Drop the now-unused `.sr-only` rule from `custom.css`.
- Rename `heroLogoDark` / `heroLogoLight` CSS module classes to
`heroLogoForLight` / `heroLogoForDark` so the class name describes
which mode shows the logo, not the asset's visual style.
- Use `useBaseUrl('/')` for the 404 "Go to Home" link so it survives
non-root `baseUrl` deployments. (`<Link to="/">` does NOT rewrite
against baseUrl.)
- Refactor `<feature.icon>` JSX dot-access (unusual lookup pattern) to
destructure `{ Icon }` and render `<Icon />`. Reads as the standard
component-namespace convention.
- Drop the `padding: 0 1.5rem` and `max-width: 1400px` overrides on the
navbar — they pushed the brand logo away from the viewport edge so it
didn't line up with the sidebar's content below it. With Docusaurus
defaults the logo now sits flush at the sidebar's left edge.
`npm run docs:build` passes cleanly.
Co-authored-by: Cursor <cursoragent@cursor.com>
jeffredodd
changed the title
|
Reopening as a fresh PR for review — see new PR (link to follow). |
|
Superseded by #1943 for a clean review. |
Summary
Stands up a Docusaurus site under
docs-site/that serves the existingdocs/content. The actual content underdocs/is the same asmain— this PR is purely the plumbing: the site that renders it, the build pipeline, the styling, and the supporting cleanup. Subsequent PRs will iterate on the docs themselves through this new site.Why
Migrating off the ReadMe.com pipeline (already removed from
mainin #1940) leaves a gap: there's nowhere for docs to render. This PR fills that gap with a self-hosted Docusaurus site that:onBrokenLinks: 'throw',onBrokenAnchors: 'throw') so docs regressions fail the buildWhat's in this PR
Docusaurus site (
docs-site/)@docusaurus/preset-classicreading from the existing top-leveldocs/directory@easyops-cn/docusaurus-search-local(no external service required)docs-site/src/pages/index.tsx) with hero, features grid, and quick-links sectiondocs-site/src/theme/NotFound/Content/index.tsx) with curated suggestionsRoot-level scripts
Cleanup folded in
docs/reference/jobs-and-compensations.md(../../src/foo.tsx-style refs that resolved outside the served site) replaced with plain code spans so the build's broken-link check passes<header>/<main>landmarks, fix duplicate alt text, replace ad-hoc `sr-only` with proper aria-label)What's NOT in this PR (intentionally)
docs/files (other than the one broken-link fix). Reorganizing, rewriting, or expanding the existing top-level sections is follow-up work.urlis stillhttp://localhostindocusaurus.config.ts. Choosing a host and wiring CI/CD is a follow-up.How to preview locally
Production build smoke-check:
Both succeed with zero warnings / zero errors on this branch.
Also included: unrelated Dashboard fix
This branch also carries #1937 (`fix(Dashboard): close review modal when all pending changes are cancelled`) which was merged via this branch's history. It's a small, self-contained bug fix in
JobAndPayView.tsxplus 130 lines of pending-change test coverage — orthogonal to the docs migration but already approved.Sc